Multi-project workspaces

Visual Studio Code can open several folders in one workspace. STM32CubeIDE for Visual Studio Code uses this capability for projects that must be developed together, such as dual-core applications, related examples, or firmware and test projects.

Use a multi-project workspace only when the projects have a practical relationship. For unrelated projects, separate Visual Studio Code windows reduce context mistakes.

A multi-project workspace is a coordination tool. It does not merge the projects into one build system unless tasks, CMake files, or scripts explicitly do that work.

Common use cases

Multi-project workspaces are useful for these cases:

  • Dual-core applications with one project for each core

  • A bootloader project and an application project

  • A firmware project and a test or validation project

  • Several examples used to compare board or middleware behavior

The workspace keeps the related folders visible together and lets Visual Studio Code store the group in a .code-workspace file.

This arrangement is useful when developers must inspect shared headers, compare generated files, or run build and debug commands across related targets during the same session.

Context selection

In a multi-project workspace, always verify which project receives the command. Build, debug, discovery, and setup commands can use the currently selected folder, preset, or launch configuration.

The active editor tab is not always enough to identify the command target. Some commands use the selected folder in the Explorer view, while others use the active CMake project or selected debug configuration.

Before running a project command, check these items:

  • Active folder in the Explorer view

  • Selected project in the CMake view

  • Selected CMake configure preset

  • Selected build target

  • Selected debug launch configuration

This check prevents building or flashing the wrong STM32 target.

If the workspace includes several connected boards, use clear launch configuration names that include the board or core name. Clear names make the debug selection safer during repeated test cycles.

Workspace file

A .code-workspace file stores the folders that belong to a workspace. It can also store workspace-level settings that apply to all folders in the group.

Use workspace-level settings for shared behavior across the group. Use folder-level .vscode files when a setting belongs to only one project.

Store the workspace file near the related project folders when the relationship is part of the product structure. This placement makes the workspace discoverable for new developers and for source-control review.

Build and debug order

Some multi-project workspaces require an explicit order. For example, a bootloader can require a completed application image before packaging, or a dual-core project can require both core images before flashing.

Document the required order in workspace tasks or project documentation. If a task builds several projects, give the task a clear name and verify that it uses the correct folder for each command.

For ordered workflows, prefer explicit tasks over manual memory. A named task such as Build bootloader and application is easier to repeat and easier to review than a sequence of undocumented commands.